This PR resolves critical BLE connection issues with Switchbot Curtain 3 devices on Raspberry Pi HomeBridge that were causing "No characteristics available" errors and NaN position values in HomeKit.

Root Cause Analysis

The issues stemmed from multiple problems in the BLE handling code:

1. Unsafe array access: The code was accessing deviceList[0] without checking if the device discovery returned any devices
2. Invalid position calculations: Position values were calculated as 100 - this.serviceData.position even when position was undefined/null, resulting in NaN
3. Logic errors: Validation conditions used OR instead of AND logic (!== undefined || !== null)
4. Poor error recovery: Limited fallback mechanisms when BLE consistently failed

Example of the Problem

From the original issue logs:

[04/08/2025, 15:22:38] [SwitchBot] Curtain3: Bedroom Left Curtain Error: No characteristics available.
[04/08/2025, 15:22:50] [@switchbot/homebridge-switchbot] This plugin generated a warning from the characteristic 'Current Position': characteristic value expected valid finite number and received "NaN" (number).

Changes Made

1. Device Discovery Validation

Before:

.then(async (device_list: SwitchbotDevice[]) => {
  const deviceList = device_list as WoCurtain[]
  return await deviceList[0].runToPos(100 - Number(this.WindowCovering.TargetPosition), adjustedMode)
})

After:

.then(async (device_list: SwitchbotDevice[]) => {
  const deviceList = device_list as WoCurtain[]
  if (deviceList && Array.isArray(deviceList) && deviceList.length > 0) {
    return await deviceList[0].runToPos(100 - Number(this.WindowCovering.TargetPosition), adjustedMode)
  } else {
    throw new Error('No device found')
  }
})

2. Position Data Validation

Before:

if ('position' in this.serviceData) {
  this.WindowCovering.CurrentPosition = 100 - this.serviceData.position
}

After:

if ('position' in this.serviceData && this.serviceData.position !== undefined && 
    this.serviceData.position !== null && !isNaN(Number(this.serviceData.position))) {
  this.WindowCovering.CurrentPosition = 100 - Number(this.serviceData.position)
} else {
  this.warnLog(`Invalid position data from BLE: ${this.serviceData.position}`)
}

3. HomeKit NaN Prevention

Added validation in updateHomeKitCharacteristics():

if (isNaN(Number(this.WindowCovering.CurrentPosition))) {
  this.warnLog(`CurrentPosition is NaN, keeping previous value`)
  this.WindowCovering.CurrentPosition = this.accessory.context.CurrentPosition ?? 100
}

4. Logic Corrections

Fixed validation conditions throughout:

// Before: if (context !== undefined || context !== null)
// After: if (context !== undefined && context !== null)

5. Enhanced Error Handling

Improved BLE connection error messages and added guidance for users to consider using BLE/OpenAPI connection type as fallback.

Impact

• Resolves "No characteristics available" errors during device discovery
• Prevents HomeKit warnings about NaN position values
• Provides better error recovery for unstable BLE connections on Raspberry Pi
• Maintains backward compatibility with existing configurations
• Applied the same device list validation fix to BlindTilt devices

Testing

• All existing tests pass
• Build completes successfully without errors
• Edge case validation implemented and tested
• No breaking changes introduced

Fixes #1226.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.